Split Buttons

IN THIS PAGE

Create a Split Button
arguments[1]
Make a Split Button with a Menu

Description

Split buttons are comprised of one button divided into two parts. This arrangement provides users the option of running an action or selecting the action to run.

An example of a split button.

The 'Create New Component' button on the Web Projects Control Panel, shown above, is one example of a split button. When you press the main button, represented by an icon, you will open the specified component builder. When you press the second button, designated with an down arrow, you will open a dropdown where you can select a different component type. Once a given component type is selected, that selection will be displayed in the first button's space. Split buttons are described in this video and in the guide below.

Create a Split Button

In the UX Builder, on the UX Controls page, open the 'Other Controls' menu. Click on the [Button] option to add a button control to the component.
Highlight the button. In the properties list on the right, in the 'Button Properties' section, click the dropdown next to the 'Advanced button control type' property and select 'Button'.
In the 'Button Appearance' section check the 'Has dropdown icon' checkbox.
Next check the 'Display as split button' checkbox that appears.
Run the component in Live Preview. You should see a split button, but the button does not yet do anything.

arguments[1]

In the event handler you can use 'arguments[1]' to determine which part of the split button was clicked on. This can be set to either 'split' or 'normal'. With split buttons it is necessary to define the event handler in the 'onClick' event in the 'Javascript' section. Do not use the abstract 'click' event. In order to see which portion of a split button was clicked on you can use the following javascript alert in the buttons 'onClick' event.

alert('You clicked on the ' + arguments[1] + 'button');

When the component is run, this will return an alert that will state that the you clicked on the 'normal' or the 'split' part of the button. This logic will be used in the example below to create a menu.

Make a Split Button with a Menu

Highlight the split button in the controls tree. In the properties list on the right scroll down to the 'Javascript' section. Click the [...] button next to the 'onClick' property.
In the 'Edit onClick Event' dialog select the 'Text mode' radio button from the 'Editing mode' options. Add the following javascript and click the 'Save' button.
```
var buttonId = this.id;
buttonId = this.id.split('V.R1.')[1];

if(arguments[1] == 'split') {
     var ele = {dialog.object}.getPointer(buttonId);
     {dialog.object}.runAction('showMenu',ele);
} else { 
     var btn = {dialog.object}.getControl(buttonId);
     if(typeof btn._state != 'undefined') {
          alert('run ' + btn._state);
     } else {
          alert('run the default action');
     }
}
```
First,'this.id' returns the button's full id, that includes not only the ID listed in the 'Button Properties' but also the group name id (see the 'Dynamically Changing a Button's Code' page), 'DLG.V.R1.BUTTON_1'. To get the button id, this code makes use of the javascript split() function, which splits a string into an array of substrings and then returns a new array. The split is performed on 'this.id' and returns all of the text that comes after 'V.R1'. This returned array is assigned to the variable 'buttonId'. An 'If' statement then determines whether the user clicked on the 'split' portion of the split button, i.e. the dropdown arrow. If this is true then a variable named 'ele' gets a pointer to the button and an action called 'showMenu' is run. The action will show a dropdown menu. The 'ele' variable is passed into the action in order to specify where the button is located in this menu. An 'else' statement handles what to do if the user clicks on the 'normal' part of the split button. If this happens, a variable 'btn' gets a pointer to the button. Another 'if' statement then looks to see if the button's state has been defined, i.e. if one of the menu options has been selected. If it has been defined, then the action that corresponds to the button's state is run. Otherwise, a second 'else' statement runs the default action.
On the Controls page toolbar click the 'Menu' dropdown to open the additional options menu. Select the 'Javascript Actions Editor' option.
Click the 'Add New Action' button.
Give the new action the name 'showMenu' and click OK.
Highlight the 'showMenu' action and click the 'Edit Action' button.
In the 'Edit Unbound Event' dialog click the 'Add New Action' button.
Type 'menu' into the filter control and select the 'Menus' action. Click OK.
In the 'Action Javascript - Dropdown Menu' properties dialog view the 'Menu Choices' section. Click the [...] button next to the 'Menu definition' property.
Click the 'Add item - Sibling' in the lower left-hand corner of the 'Tree Data Genie'.
Add the following items to the 'Add item' dialog's 'Label' section.
```
Option 1
Option 2 
Option 3
```
Highlight the first item, 'Option 1', in the Tree Data Genie. In the 'Leaf Properties' section on the right click the [...] button next to the 'onClick' property.
Set the 'Edit action' definition to be the following code and click OK.
```
setSplitMenuChoice('BUTTON_1','Option 1');
```
This function passes in the name of the button and the action to be run, 'Option 1'.
Highlight the second item in the Tree Data Genie, 'Option 2', and again click the [...] button next to the 'onClick' property in the Leaf Properties section.
Set the 'Edit action' definition for the second item to be the following code and click OK.
```
setSplitMenuChoice('BUTTON_1','Option 2');
```
Highlight the third item in the Tree Data Genie, 'Option 3'. Click the [...] button nex to the 'onClick' property in the 'Leaf Properties' section on the right.
Add the following code to the onClick event definition for the third item and click OK. Click OK again to close the Tree Data Genie. Click OK, OK, Save, and OK to return to the Controls page.
```
setSplitMenuChoice('BUTTON_1','Option 3');
```
In the main menu expand the 'Code' section and click to open the 'Javascript functions' page.
Define the 'setSplitMenuChoice() function using the following code.
```
function setSplitMenuChoice(buttonId, actionName) {
var btn = {dialog.object}.getControl(buttonId);
btn.setContent({html : actionName, tip: 'Help for action' + actionName, icon: ''});
btn._state = actionName;
setTimeout(function(){
     {dialog.object}.buttonClick(butonId);
     },10);
}
```
The setSplitMenuChoice() function defined here takes the button id and a specified action as arguments. In this case the action will be either 'Option 1', 'Option 2', or 'Option 3', the choices defined in the menu action. A variable named 'btn' gets a pointer to the button object using the buttonId argument. The setContent() function is then called. This function updates the text, image, and bubble help for the 'normal' or 'main' portion of the split button. The name of the action that was selected ('Option 1', 'Option 2', or 'Option 3') is then stored in a variable in the button object. In this way, when the users clicks on the button again, the state of the button can be determined. The 'buttonClick' method executes the selected action. The setTimeout() function wrapped around the buttonClick() function simply gives the menu time to close down.
Run the component in Live Preview. Click on the main 'Button' button. An alert should be displayed stating that this is the default button.
Now click the Dropdown and select an option. The selection that you make should fill the main button.
Click on the main button again. You should see an alert specific to the option that you selected.